home *** CD-ROM | disk | FTP | other *** search
/ MacHome 2001 May / MacHome CD (May 2001).iso / mac / Stuff / Software / Tools / Black & Bleu™ 3.0 / For Developers / Usage Example / BleuRoseErrors.c < prev    next >
Encoding:
C/C++ Source or Header  |  2000-09-09  |  11.9 KB  |  348 lines  |  [TEXT/CWIE]
  1. /*    BleuRoseErrors.c - This file defines the interface to
  2.                     the Bleu Rose Ltd. Error Library
  3.  
  4.     Copyright 2000 Bleu Rose Ltd. All Rights Reserved.
  5.  
  6.     Author:        Gary Rice
  7.  
  8.     Created:    September 9, 2000 - Original development environment:
  9.                     CodeWarrior/Pro v5.3
  10.                     Mac OS v7.6.1
  11.  
  12.     Modified:    N/A
  13.  
  14.     Licensing Notes:
  15.         You may incorporate this source code into your
  16.         applications without restriction.
  17.  
  18.         You are NOT permitted to redistribute the source,
  19.         compiled binaries or the library that the code
  20.         references without first licensing the package
  21.         represented by this source file from Bleu Rose Ltd.
  22.  
  23.         Licensing information was packaged with the files
  24.         that this file was part of. If that licensing information
  25.         is no longer included in the files you have, you may obtain
  26.         another copy by sending EMail to licensing@bleurose.com
  27.         and asking for the Error Library Licensing Package.
  28.  
  29.     Usage Notes:
  30.         Refer to the sample file "main.c" for an example of how
  31.         to use these routines.
  32.         
  33.         The efficiency of these routines can be improved by adding
  34.         code that saves the code resource in memory rather than
  35.         locating and loading the code resource each time the routines
  36.         are accessed.
  37.  
  38. ******************************************************************/
  39.  
  40. #include <SegLoad.h>
  41.  
  42. #include "BleuRoseErrors.h"
  43.  
  44. /****************************************************************
  45.     Routine:    FindBleuRoseErrorLibrary
  46.     Purpose:    Locates the Bleu Rose Ltd. Error Library so that it can
  47.                 be accessed as a code resource
  48.     Algorithm:    Attempt to locate the BleuRoseErrorLib code resource in:
  49.                 1) Your application
  50.                 2) The same folder as your application (in a separate file
  51.                         called BleuRoseErrorLib)
  52.                 3) Extensions folder as a separate file called BleuRoseErrorLib
  53.     Inputs:        None
  54.     Outputs:    A pointer to the FSSpec for BleuRoseErrorLib - If the resource
  55.                 is included in the application itself, the FSSpec will be empty
  56.                 but the status returned will be "noErr"
  57.     Status:        0            = noErr        Success
  58.                 -43            = fnfErr    Could not locate the Error Library
  59.                 -192        = resNotFound
  60.                                         Could not locate the Error Library Code Resource
  61.                 Any other error returned by ResError ()
  62.                 -2147483644 =  kErrorResMissing
  63.                                         The error TEXT resource is missing. */
  64.                 
  65. OSStatus FindBleuRoseErrorLibrary (FSSpecPtr theLibrary)
  66. {
  67.     Handle        libraryRes = nil;
  68.     FCBPBRec    paramBlock;
  69.     Str31        appName;
  70.     FSSpec        tmpFile;
  71.     OSStatus    result = (OSStatus)noErr;
  72.     long        resSize;
  73.     long        foundDirID;
  74.     short        foundVRefNum;
  75.     short        libraryResNum;
  76.     short        saveCurResFileRefNum = CurResFile ();
  77.     
  78.     /* Make sure we start with a clean data structure */
  79.     theLibrary->vRefNum = 0;
  80.     theLibrary->parID = 0;
  81.     theLibrary->name[0] = 0;
  82.     
  83.     /* Test for CurResFile errors */
  84.     result = (OSStatus)ResError ();
  85.     if (result)
  86.         return result;
  87.     
  88.     /* Convert the refnum of the app into an FSSpec */
  89.     libraryResNum = LMGetCurApRefNum ();
  90.     paramBlock.ioCompletion = nil;
  91.     paramBlock.ioNamePtr    = appName;
  92.     paramBlock.ioVRefNum    = 0;
  93.     paramBlock.ioRefNum        = libraryResNum;
  94.     paramBlock.ioFCBIndx    = 0;
  95.     result = (OSStatus)PBGetFCBInfo (¶mBlock, false);
  96.     if (result)
  97.         return result;
  98.         
  99.     /* Look inside the current application for the library first */
  100.     result = FSMakeFSSpec (paramBlock.ioFCBVRefNum, paramBlock.ioFCBParID, appName, &tmpFile);
  101.     if (result)
  102.         return result;
  103.     
  104.     /* Look for the main error resource */
  105.     UseResFile (libraryResNum);
  106.     libraryRes = Get1Resource (kBleuRoseErrorLibListType, kBleuRoseErrorLibCommonResID);
  107.     if (!libraryRes)
  108.         result = (OSStatus)resNotFound;
  109.     else
  110.         result = (OSStatus)ResError ();
  111.     
  112.     /* If we got this resource assume that the library is inside the application.
  113.         If the size isn't reasonable, assume that the library has not been populated. */
  114.     if (result == (OSStatus)noErr)
  115.     {
  116.         resSize = GetResourceSizeOnDisk (libraryRes);
  117.         if (resSize < kEstimatedErrorResSize)
  118.         {
  119.             /* Reset to what we started with */
  120.             UseResFile (saveCurResFileRefNum);
  121.             return (kErrorResMissing);
  122.         }
  123.     }
  124.     
  125.     /* If the application doesn't have the error library
  126.         inside, look for it in the application's folder
  127.         as a stand-alone file */
  128.     if (result)
  129.     {
  130.         /* open the resource fork of the Error Library */
  131.         BlockMoveData (kBleuRoseErrorLibFileName, tmpFile.name, 17);
  132.         libraryResNum = FSpOpenResFile (&tmpFile, fsRdPerm);
  133.         if (libraryResNum != -1)    /* Must have found a file */
  134.         {
  135.             /* Look for the main error resource */
  136.             UseResFile (libraryResNum);
  137.             libraryRes = Get1Resource (kBleuRoseErrorLibListType, kBleuRoseErrorLibCommonResID);
  138.             if (!libraryRes)
  139.                 result = (OSStatus)resNotFound;
  140.             else
  141.                 result = (OSStatus)ResError ();
  142.     
  143.             /* If we got this resource assume that the library is inside the application.
  144.                 If the size isn't reasonable, assume that the library has not been populated. */
  145.             if (result == (OSStatus)noErr)
  146.             {
  147.                 resSize = GetResourceSizeOnDisk (libraryRes);
  148.                 if (resSize < kEstimatedErrorResSize)
  149.                 {
  150.                     /* Reset to what we started with */
  151.                     UseResFile (saveCurResFileRefNum);
  152.                     return (kErrorResMissing);
  153.                 }
  154.             }
  155.             
  156.             /* If everything is OK, set up the library FSSpec */
  157.             if (result == (OSStatus)noErr)
  158.             {
  159.                 BlockMoveData (tmpFile.name, theLibrary->name, tmpFile.name[0]+1);
  160.                 theLibrary->vRefNum = tmpFile.vRefNum;
  161.                 theLibrary->parID = tmpFile.parID;
  162.             }
  163.         
  164.             CloseResFile (libraryResNum);
  165.         }
  166.         else    /* No file in this directory */
  167.         {
  168.             result = (OSStatus)ResError ();
  169.             if (result == (OSStatus)noErr)
  170.                 result = (OSStatus)resNotFound;
  171.         }
  172.     }
  173.     
  174.     /* If the application folder doesn't have the error library inside,
  175.     look for it in the Extensions folder as a stand-alone file */
  176.     if (result)
  177.     {
  178.         /* Get the Extensions folder volume and directory info */
  179.         result = (OSStatus)FindFolder (kOnSystemDisk, kExtensionFolderType, kDontCreateFolder,
  180.                                         &foundVRefNum, &foundDirID);
  181.         if (result == (OSStatus)noErr)
  182.         {
  183.             /* Turn the Extensions info into an FSSpec */
  184.             result = (OSStatus)FSMakeFSSpec (foundVRefNum, foundDirID, kBleuRoseErrorLibFileName,
  185.                                         &tmpFile);
  186.             if (result == (OSStatus)noErr)
  187.             {
  188.                 /* open the resource fork of the Error Library */
  189.                 libraryResNum = FSpOpenResFile (&tmpFile, fsRdPerm);
  190.                 if (libraryResNum != -1)    /* Must have found a file */
  191.                 {
  192.                     /* Look for the main error resource */
  193.                     UseResFile (libraryResNum);
  194.                     libraryRes = Get1Resource (kBleuRoseErrorLibListType, kBleuRoseErrorLibCommonResID);
  195.                     if (!libraryRes)
  196.                         result = (OSStatus)resNotFound;
  197.                     else
  198.                         result = (OSStatus)ResError ();
  199.             
  200.                     /* If we got this resource assume that the library is inside the application.
  201.                         If the size isn't reasonable, assume that the library has not been populated. */
  202.                     if (result == (OSStatus)noErr)
  203.                     {
  204.                         resSize = GetResourceSizeOnDisk (libraryRes);
  205.                         if (resSize < kEstimatedErrorResSize)
  206.                         {
  207.                             /* Reset to what we started with */
  208.                             CloseResFile (libraryResNum);
  209.                             UseResFile (saveCurResFileRefNum);
  210.                             return (kErrorResMissing);
  211.                         }
  212.                     }
  213.     
  214.                     /* If everything is OK, set up the library FSSpec */
  215.                     if (result == (OSStatus)noErr)
  216.                     {
  217.                         BlockMoveData (tmpFile.name, theLibrary->name, tmpFile.name[0]+1);
  218.                         theLibrary->vRefNum = tmpFile.vRefNum;
  219.                         theLibrary->parID = tmpFile.parID;
  220.                     }
  221.                     
  222.                     CloseResFile (libraryResNum);
  223.                 }
  224.                 else    /* No file in this directory */
  225.                 {
  226.                     result = (OSStatus)ResError ();
  227.                     if (result == (OSStatus)noErr)
  228.                         result = (OSStatus)resNotFound;
  229.                 }
  230.             }
  231.         }
  232.     }
  233.  
  234.     /* Reset to what we started with */
  235.     UseResFile (saveCurResFileRefNum);
  236.     return (result);
  237. } /* FindBleuRoseErrorLibrary */
  238.  
  239. /****************************************************************
  240.     Routine:    CallBleuRoseErrorLibrary
  241.     Purpose:    - Look up an error number in the database
  242.                 - Translate an error type number into its equivalent
  243.                     error type name such as "QuickTime".
  244.     Algorithm:    Using the proposed error type as a basis, find the error that corresponds
  245.                 to the error and type specified. If there is no match for the error type
  246.                 but the error number itself is found, return the first occurrence of the
  247.                 error in the database plus a warning status. Otherwise return an error.
  248.                 
  249.                 If translating an error type number into its equivalent, Access STR# resource
  250.                 29271 (kBleuRoseErrorLibCommonResID) to translate the number into a name.
  251.     Inputs:        An FSSpec pointer connected to a valid FSSpec for the error library.
  252.                                                 and
  253.                 A BleuRoseErrorLibStructure pointer connected to a valid
  254.                 BleuRoseErrorLibStructure filled in as follows:
  255.                 Out-In Name                    Type    Description
  256.                    ->  action                    SInt32    Set to kGetError for getting an error code
  257.                                                                              or
  258.                                                         Set to kGetType for translating an error type
  259.                                                             into a string. For this option, the following
  260.                                                             fields are not used (and may be left blank):
  261.                                                                 error
  262.                                                                 actualErrorTypeNumber
  263.                                                                 pneumonic
  264.                                                                 description
  265.                    ->  error                    SInt32    The error number to look up
  266.                    ->  proposedErrorTypeNumber    SInt16    The Error Type value to try
  267.                   <-   actualErrorTypeNumber    SInt16    The Error Type value matching the error found
  268.                   <-   errorTypeName            Str255    Name string matching the Error Type number
  269.                   <-   pneumonic                Str255    Apple's name for this error
  270.                   <-   description                Str255    Apple's explanation of this error
  271.                                                     
  272.                 The proposedErrorTypeNumber value is a number from 0 (k1stErrorTypeFound) through
  273.                 kZlastType-1. Constants are defined in "BleuRoseErrors.h" for each of the error
  274.                 types in the database.
  275.     Outputs:    See above
  276.     Status:        0            = noErr        Success
  277.                 -43            = fnfErr    Could not find the Error Library
  278.                 -109        = nilHandleErr
  279.                                         Could not find the code resource in the Error Library
  280.                 2147483646    = kWarningErrorNotDescribed
  281.                                         The error was on file but contained no explanation.
  282.                                         A substitute explanation string was used.
  283.                 2147483643    = kWarningErrorNotRequestedType
  284.                                         There was an error on file but it doesn't match the
  285.                                         type of error you specified. The error entry has been
  286.                                         filled in with the information about the error that
  287.                                         was found.
  288.                 2147483645    = kWarningErrorNotDescribedAndNotRequestedType
  289.                                         Both warnings (above) apply.
  290.                 -2147483646    = kErrorTypeResMissing
  291.                                         The error type STR# resource 21077 is missing
  292.                 -2147483647    = kErrorTypeNotOnFile
  293.                                         The error type you specified is not on file
  294.                                         in the database. The type value must be from
  295.                                         0 (k1stErrorTypeFound) <= type value < kZlastType
  296.                 -2147483648    = kErrorNotOnFile
  297.                                         The error number you supplied is not on file in
  298.                                         the database.                                    */
  299.  
  300. OSStatus CallBleuRoseErrorLibrary (FSSpecPtr theLibrary, BleuRoseErrorLibStructurePtr errorInfo)
  301. {
  302.     OSStatus    status;
  303.     Handle         codeRes = nil;
  304.     short        libraryResNum = 0;
  305.     short        saveCurResFileRefNum = 0;
  306.     
  307.     /* If the FSSpec has been filled in, assume that the code resource is in a separate file
  308.     and NOT part of the current application */
  309.     if (theLibrary->name[0] != 0)
  310.     {
  311.         saveCurResFileRefNum = CurResFile ();
  312.         /* open the resource fork of the Error Library */
  313.         libraryResNum = FSpOpenResFile (theLibrary, fsRdPerm);
  314.         if (libraryResNum == -1)    /* Must have had a problem */
  315.         {
  316.             status = (OSStatus)ResError ();
  317.             return status;
  318.         }
  319.         
  320.         UseResFile (libraryResNum);
  321.     }
  322.     
  323.     /* Load the code resource */
  324.     codeRes = Get1Resource (kBleuRoseErrorLibResType, kBleuRoseErrorLibCommonResID);
  325.     if (codeRes)
  326.     {
  327.         /* Lock the resource in high memory and execute it */
  328.         HLockHi (codeRes);
  329.         status = CallBleuRoseErrorLibProc ((BleuRoseErrorLibProcUPP)*codeRes, errorInfo);
  330.         HUnlock (codeRes);
  331.     }
  332.     else    /* Oops. No code resource */
  333.     {
  334.         status = (OSStatus)ResError ();
  335.         if (!status)
  336.             status = (OSStatus)nilHandleErr;
  337.     }
  338.     
  339.     /* If the library was in a separate file, close it */
  340.     if (libraryResNum)
  341.         CloseResFile (libraryResNum);
  342.     
  343.     /* Reset the environment */
  344.     if (saveCurResFileRefNum)
  345.         UseResFile (saveCurResFileRefNum);
  346.             
  347.     return status;
  348. } /* CallBleuRoseErrorLibrary */